feat(club-003): club POS integration: identify member and register cashback from sales

work/artifacts/CLUB-003/documenter.md

@@ -0,0 +1,22 @@
+# CLUB-003 — Documentation notes
+
+## New endpoint
+- `GET /club/resolve?memberCode=MDV-XXXXXXXX` — resolves an active Club member by code. Returns `{ member, config }` or 404.
+
+## POS sale integration
+- `POST /pos/sales` accepts optional `clubMemberId: string` (UUID of the Club member).
+- When the sale completes (`state: 'COMPLETED'`):
+  - reads `club_cashback_bps` from `store_settings`
+  - computes `cashbackCents = round(totalCents * cashbackBps / 10_000)`
+  - inserts into `club_transactions` with `idempotency_key = club-earn-{orderId}`, `type = 'earn'`
+- Sale response includes `clubEarnedCents` and `clubMemberCode`.
+
+## Idempotency contract
+- Each completed sale generates exactly one ledger entry per member.
+- If the same sale is retried (same idempotency key on POST /pos/sales), the ledger entry is not duplicated (`ON CONFLICT DO NOTHING`).
+- Failed ledger writes do not block the sale.
+
+## Out of scope for CLUB-003
+- Club member lookup UI in the TPV terminal frontend (API ready; UI pending).
+- Cashback refund when items are returned (CLUB-004).
+- Redeem balance at POS.