docs: update README and add CLAUDE.md for finance app

README.md

@@ -58,7 +58,8 @@ One row per line item within a statement. Cascade-deleted when the parent statem
 | Column | Type | Description |
 |--------|------|-------------|
 | `id` | int | Primary key |
-| `statement_id` | int FK → `statements` | Parent statement |
+| `statement_id` | int FK → `statements` (nullable) | Parent statement; NULL for manually-entered transactions |
+| `owner_id` | int FK → `participants` (nullable) | Owner for manual transactions (no statement); statement-linked transactions derive owner from `statements.owner_id` |
 | `transaction_date` | date | Date of transaction |
 | `description` | text | Raw description from the statement |
 | `amount` | numeric | Original amount in statement currency |
@@ -164,8 +165,9 @@ Saved auto-categorisation rules. Applied in bulk via the Rules page.
 | `enabled` | bool | |
 | `priority` | int | Higher priority rules run first |
 
-**Condition fields**: `merchant_normalized`, `description`, `category`, `bank_name`, `amount`
+**Condition fields**: `merchant_normalized`, `description`, `category`, `bank_name`, `amount`, `transaction_type`
 **Condition operators**: `contains`, `equals`, `starts_with`, `gt`, `lt`, `not_equals`
+**Actions**: `set_category`, `set_merchant`, `add_tag_ids`, `apply_split`
 
 ---
 
@@ -289,6 +291,26 @@ docker exec postgres-personal psql -U personal -d personal \
 | `0007_cashflow` | `amount_aud`, `exchange_rate_to_aud` on transactions; `exchange_rate_to_aud` on statements |
 
 > `paperless_doc_id` on statements and the `uq_statements_paperless_doc_id` index were added directly (not tracked in a migration file).
+> `owner_id` on transactions and `statement_id` made nullable were applied directly (March 2026) to support manual transaction entry without a fake statement.
+
+---
+
+## Known Gaps / TODOs
+
+### Payment Provider tracking
+
+Currently `merchant_normalized` conflates the *payment provider* with the *merchant*. Transactions processed through PayPal, Afterpay, Zip, Alipay, etc. end up with the provider as the merchant when the real merchant can't be recovered.
+
+**What's been done so far:**
+- PayPal entries that embed the merchant name (e.g. `PAYPAL *BUNNINGSGRO`) were cleaned up — the real merchant was extracted during the March 2026 consolidation pass.
+- Pure PayPal/Afterpay/Zip entries where the merchant is unrecoverable were left as-is.
+- A one-time SQL consolidation pass normalised ~50 merchant name variant groups (March 2026).
+
+**Remaining work:**
+1. **DB migration**: `ALTER TABLE transactions ADD COLUMN payment_provider text` and same on `transaction_overrides`.
+2. **Gemini prompt**: add `payment_provider` to the `responseSchema` so the AI extracts it separately (`"PayPal"`, `"Afterpay"`, `"Zip"`, `null`, etc.) — the raw bank description usually contains enough signal.
+3. **Backfill**: for existing transactions, derive `payment_provider` from `merchant_name` patterns (`PAYPAL *`, `AFTERPAY`, `ZIP/ZIPPAY`, `BPAY`).
+4. **App**: surface `payment_provider` as a filter/column in the transactions view; exclude payment providers from merchant analytics so they don't inflate the merchant list.
 
 ---