feat: real-time multiplayer race mode (free, prestige, crypto)

Adds a complete block-cadence multiplayer race mode alongside solo and tavern.
  Disabled by default; enable with MATCH_ENABLED=true.

  Highlights:
  - New shared engine: MatchRoom, MatchEngine, MatchState (transport-agnostic, unit-tested).
  - Per-economy queues: free, credits_prestige, crypto_race with atomic escrow/refund.
  - MatchScheduler drains queues on every new block and starts 2–32 player races.
  - MatchManager handles Socket.IO lifecycle, server-authoritative movement, reconnect grace,
    forfeit/AFK handling, and end-of-match persistence.
  - Crypto races use race-entry tickets (grants.race_entries) to avoid on-chain refunds; winner
    payout is queued through the existing batch payout/retry service.
  - Leaderboard integration: free → Pleb, prestige → /api/leaderboard?board=prestige,
    crypto → Hall of Champions.
  - Tavern integration: Queue for Race panel, active race list, and live spectator rendering.
  - Dedicated /match.html client with economy selector, race HUD, and post-match scoreboard.
  - Migration 022 adds matches, match_entrants, match_events, match_queue_entries,
    race_entry_transactions, users.race_entries, and payouts.match_id.

  Docs:
  - New docs/MATCH_MODE.md with full architecture, config, events, and operational notes.
  - Updated README.md, docs/TAVERN_AND_MULTIPLAYER.md, docs/TODO.md, src/.env.example,
    and src/.env.

  Tests: 40 new unit tests across 7 suites, all passing.

  Known follow-ups for real-world validation:
  - Full integration test with Postgres + Socket.IO.
  - Server boot check with MATCH_ENABLED=false (default) to ensure solo/tavern remain unaffected.
  - Browser render-kit verification in /match.html and tavern spectator.
  - Crypto-race payout end-to-end with real wallet-rpc.

src/.env.example

@@ -487,3 +487,34 @@ CRYPTO_TYPE=WOW
 TAVERN_ENABLED=false
 # Server-tick / snapshot broadcast cadence in ms (default 100 = 10 Hz)
 # TAVERN_TICK_MS=100
+
+# =============================================================================
+# Match mode (multiplayer races)
+# =============================================================================
+# Enable real-time multiplayer races. Solo/Tavern are unaffected.
+MATCH_ENABLED=false
+
+# Max players per race (2–32). Default 4.
+# MATCH_MAX_PLAYERS=4
+
+# Server tick interval in ms (default 250 = 4 Hz).
+# MATCH_TICK_MS=250
+
+# Minimum race duration in ms before the next block can end it (default 20s).
+# MATCH_MIN_DURATION_MS=20000
+
+# Hard ceiling in ms after which a race is force-ended (default 4m).
+# MATCH_HARD_CEILING_MS=240000
+
+# Credits cost for prestige-only races (default 1).
+# MATCH_CREDITS_COST=1
+
+# Crypto race house fee percent (default 5).
+# MATCH_HOUSE_FEE_PERCENT=5
+
+# Optional override for the crypto-race per-player entry fee in atomic units.
+# If unset, the existing per-game price (DIRECT_GAME_PRICE / SINGLE_GAME_PRICE) is used.
+# MATCH_ENTRY_FEE_ATOMIC=5000000000
+
+# Enable crypto race-entry ticket economy (requires paid instance + ticket products).
+# MATCH_CRYPTO_RACE_ENABLED=false