Fix payment review round 3: saved-card idempotency, stale-pending sweep, webhook fail-closed

R1/R4: saved_card branch in CreateTerminalPayment now mirrors CreateTipPayment
- advisory lock (crussell:payment:<bookingID>) serializes concurrent double-clicks
- deterministic key bookingID-sc-type-amount-cardID (<=45 chars) so a lost-response
  retry derives the same key and dedups instead of double-charging
- idempotency switch inside the lock: completed -> dedup, pending -> reuse with
  pence amount-guard, failed -> clean 409
- success response includes card_brand/card_last4 (frontend already reads them)

R2: add 'failed' case to all four retry switches (tip, booking, gift card, till)
- a swept/definitively-rejected record returns 409 instead of 500-ing on the
  idempotency_key UNIQUE constraint

R3: extend SweepStalePendingPayments to till_sales card rows
- sweeps pending till_sales (online_square/in_person_card) past Square's ~24h
  key retention, closing the double-charge window for till sales
- swept rows logged with the same CRITICAL manual-reconciliation marker as the
  refund sweep

Webhook fail-closed: reject 503 when SQUARE_WEBHOOK_SIGNATURE_KEY unset, 403 on
bad signature (was: skip verification in dev)

Refund status resolution: refunds now resolve by Square status
(COMPLETED/PENDING/FAILED/REJECTED) instead of assuming completed; real error
codes (REFUND_AMOUNT_INVALID, PAYMENT_NOT_REFUNDABLE, REFUND_ALREADY_PENDING)
added to the definitive/processed classification

HTTP client: CreateCard key truncated to <=45 chars, device_options always sent
(env SQUARE_TERMINAL_DEVICE_ID fallback), processing_fee reads amount_money,
ListCards cursor loop, refund keys hashed to <=45 chars

Other fixes: payment/till/gift-card advisory-lock + FOR UPDATE asymmetries,
GetPaymentByID NULL scans, loyalty redemption lock, card upsert on conflict,
mock ccof: prefix parity, IsValidSquareCheckoutID for real Square IDs,
isAdminRequest defense-in-depth on all 6 admin payment handlers, webhook
signature docs, M8/L5 debug markers removed

Docs: README/FC/TM/Overview updated (22 jobs, 20 CRITICAL sites, 23-section
GDPR export, sweep jobs, webhook fail-closed); P11 plan marks remaining items
(sandbox smoke test, M-8 customer_id, saved-card key dedup trade-off) as
deferred with rationale; gap backlog pruned of completed items

backend/internal/square/square_http_client_test.go

@@ -284,7 +284,9 @@ func TestCreatePaymentHTTP_TipMoneyAbsentWhenNil(t *testing.T) {
 }
 
 // TestRefundPaymentHTTP_CodeClassification verifies definitive refund rejection
-// codes map to ErrRefundDeclined, PAYMENT_ALREADY_REFUNDED maps to
+// codes (Square's documented list: REFUND_DECLINED, REFUND_AMOUNT_INVALID,
+// PAYMENT_NOT_REFUNDABLE) map to ErrRefundDeclined, the money-in-flight codes
+// (PAYMENT_ALREADY_REFUNDED, REFUND_ALREADY_PENDING) map to
 // ErrRefundAlreadyProcessed, and ambiguous errors pass through unwrapped.
 func TestRefundPaymentHTTP_CodeClassification(t *testing.T) {
 	cases := []struct {
@@ -294,9 +296,10 @@ func TestRefundPaymentHTTP_CodeClassification(t *testing.T) {
 		wantErrNil bool
 	}{
 		{name: "refund_declined", code: "REFUND_DECLINED", wantErrIs: ErrRefundDeclined},
-		{name: "amount_exceeded", code: "PAYMENT_REFUND_AMOUNT_EXCEEDED", wantErrIs: ErrRefundDeclined},
-		{name: "invalid_payment_id", code: "INVALID_PAYMENT_ID", wantErrIs: ErrRefundDeclined},
+		{name: "amount_invalid", code: "REFUND_AMOUNT_INVALID", wantErrIs: ErrRefundDeclined},
+		{name: "payment_not_refundable", code: "PAYMENT_NOT_REFUNDABLE", wantErrIs: ErrRefundDeclined},
 		{name: "already_refunded", code: "PAYMENT_ALREADY_REFUNDED", wantErrIs: ErrRefundAlreadyProcessed},
+		{name: "already_pending", code: "REFUND_ALREADY_PENDING", wantErrIs: ErrRefundAlreadyProcessed},
 		{name: "ambiguous_code", code: "INTERNAL_SERVER_ERROR", wantErrIs: nil},
 		{name: "ambiguous_non_json", code: "", wantErrIs: nil}, // raw text body
 	}
@@ -551,10 +554,15 @@ func TestCreateCardOnFileHTTP_IdempotencyKey(t *testing.T) {
 	}
 
 	sum := sha256.Sum256([]byte("user_1|cnon:test-card"))
-	wantIK := fmt.Sprintf("create-card-%x", sum)
+	wantIK := "card-" + fmt.Sprintf("%x", sum)[:38]
 	if captured["idempotency_key"] != wantIK {
 		t.Errorf("expected idempotency_key %q, got %v", wantIK, captured["idempotency_key"])
 	}
+	// Square's documented idempotency-key limit for /v2/cards is 45 chars —
+	// the truncated key must never exceed it (C-1 regression guard).
+	if len(wantIK) > 45 {
+		t.Errorf("idempotency_key %q is %d chars, exceeds Square's 45-char limit", wantIK, len(wantIK))
+	}
 	if captured["source_id"] != "cnon:test-card" {
 		t.Errorf("expected source_id cnon:test-card, got %v", captured["source_id"])
 	}