feat: wave 2 migration (P3, P5, P7 openspec changes)

Implements, verifies, and archives the three remaining Wave 2 changes from
openspec/MIGRATION-PLAN.md.

- add-wallet-settlement (P3): demo recharge, guarded withdrawal freeze and
  one-time admin review, paginated own fund entries, idempotent per-shop
  weekly/monthly settlement statements with commission rate and one-time
  payout confirmation.
- add-merchant-onboarding (P5): personal/enterprise applications with one live
  application per user, guarded review with mandatory rejection reason, and
  transactional shop + owner provisioning returning one-time credentials;
  mall onboarding/status pages and an admin review console.
- add-membership-messaging (P7): platform member levels, append-only growth
  accrual on order completion with guarded one-way leveling, order/shipment/
  refund system messages with unread/read state and soft deletion, plus the
  mall header unread badge.

Backend: migrations 0019-0023, new wallet, settlement, merchant_onboarding,
membership and messaging modules, event hooks in order/fulfillment/aftersale,
and integration suites for each. Shared contract extended and all three
frontends updated; code indexes, domain docs, backend guidelines and the
migration tracker synced.

Verification: cargo test -p vmall-api green twice consecutively; mall, admin
and shop-admin builds pass; browser smoke on every new surface; openspec
validate --all --strict green (33 passed).

The three changes share the @vmall/shared contract, the mall mock adapter and
per-app locale/nav files, so they are committed together to keep every commit
buildable.

apps/api/migrations/0020_settlement.sql

@@ -0,0 +1,62 @@
+-- Platform-mediated merchant settlement: per-shop, per-period statements
+-- snapshotted from confirmed-received orders minus completed refunds minus a
+-- platform commission. Amounts are integer minor units in the platform base
+-- currency; the rate is integer basis points and lives in platform settings.
+
+-- Settlement attributes an order to the period in which it became
+-- confirmed-received. Refunds bump orders.updated_at, so that column cannot
+-- stand in for the completion instant.
+ALTER TABLE orders ADD COLUMN completed_at TIMESTAMPTZ;
+UPDATE orders SET completed_at = updated_at
+ WHERE status = 'completed' AND completed_at IS NULL;
+CREATE INDEX orders_shop_completed_idx
+    ON orders (shop_id, completed_at) WHERE status = 'completed';
+
+CREATE TABLE platform_settings (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+INSERT INTO platform_settings (key, value)
+VALUES ('settlement.commission_rate_bps', '500')
+ON CONFLICT (key) DO NOTHING;
+
+CREATE TYPE settlement_period_kind AS ENUM ('week', 'month');
+CREATE TYPE settlement_status AS ENUM ('pending', 'confirmed');
+
+CREATE TABLE settlement_statements (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    shop_id UUID NOT NULL REFERENCES shops (id) ON DELETE CASCADE,
+    -- Statement totals are converted into and snapshotted in this currency.
+    currency CHAR(3) NOT NULL REFERENCES currencies (code),
+    period_kind settlement_period_kind NOT NULL,
+    period_start DATE NOT NULL,
+    period_end DATE NOT NULL,
+    order_count INT NOT NULL DEFAULT 0 CHECK (order_count >= 0),
+    gross_minor BIGINT NOT NULL DEFAULT 0 CHECK (gross_minor >= 0),
+    refund_minor BIGINT NOT NULL DEFAULT 0 CHECK (refund_minor >= 0),
+    commission_rate_bps INT NOT NULL
+        CHECK (commission_rate_bps >= 0 AND commission_rate_bps <= 10000),
+    commission_minor BIGINT NOT NULL DEFAULT 0 CHECK (commission_minor >= 0),
+    payable_minor BIGINT NOT NULL DEFAULT 0 CHECK (payable_minor >= 0),
+    status settlement_status NOT NULL DEFAULT 'pending',
+    generated_by UUID REFERENCES users (id),
+    confirmed_by UUID REFERENCES users (id),
+    confirmed_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT settlement_statements_period CHECK (period_end >= period_start),
+    CONSTRAINT settlement_statements_confirmed_consistent CHECK (
+        (status = 'pending' AND confirmed_by IS NULL AND confirmed_at IS NULL)
+        OR (status = 'confirmed' AND confirmed_by IS NOT NULL AND confirmed_at IS NOT NULL)
+    )
+);
+
+-- At most one statement per shop, period kind, and period start.
+CREATE UNIQUE INDEX settlement_statements_period_idx
+    ON settlement_statements (shop_id, period_kind, period_start);
+CREATE INDEX settlement_statements_shop_idx
+    ON settlement_statements (shop_id, created_at DESC);
+CREATE INDEX settlement_statements_status_idx
+    ON settlement_statements (status, created_at DESC);