v3.0.0: V3 features, server refactoring, and documentation overhaul

- Extract WebSocket handlers from main.py into handlers.py
- Add V3 feature docs (dealer rotation, dealing animation, round end reveal,
  column pair celebration, final turn urgency, opponent thinking, score tallying,
  card hover/selection, knock early drama, column pair indicator, swap animation
  improvements, draw source distinction, card value tooltips, active rules context,
  discard pile history, realistic card sounds)
- Add V3 refactoring docs (ai.py, main.py/game.py, misc improvements)
- Add installation guide with Docker, systemd, and nginx setup
- Add helper scripts (install.sh, dev-server.sh, docker-build.sh)
- Add animation flow diagrams documentation
- Add test files for handlers, rooms, and V3 features
- Add e2e test specs for V3 features
- Update README with complete project structure and current tech stack
- Update CLAUDE.md with full architecture tree and server layer descriptions
- Update .env.example to reflect PostgreSQL (remove SQLite references)
- Update .gitignore to exclude virtualenv files, .claude/, and .db files
- Remove tracked virtualenv files (bin/, lib64, pyvenv.cfg)
- Remove obsolete game_log.py (SQLite) and games.db

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -20,13 +20,19 @@ DEBUG=false
 # Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
 LOG_LEVEL=INFO
 
+# Environment name (development, staging, production)
+ENVIRONMENT=development
+
 # -----------------------------------------------------------------------------
 # Database
 # -----------------------------------------------------------------------------
 
-# SQLite database for game logs and stats
-# For PostgreSQL: postgresql://user:pass@host:5432/dbname
-DATABASE_URL=sqlite:///games.db
+# PostgreSQL connection URL (event sourcing, game logs, stats)
+# For development with Docker: postgresql://golf:devpassword@localhost:5432/golf
+DATABASE_URL=postgresql://golf:devpassword@localhost:5432/golf
+
+# PostgreSQL URL for auth/stats features (can be same as DATABASE_URL)
+POSTGRES_URL=postgresql://golf:devpassword@localhost:5432/golf
 
 # -----------------------------------------------------------------------------
 # Room Settings
@@ -42,7 +48,7 @@ ROOM_TIMEOUT_MINUTES=60
 ROOM_CODE_LENGTH=4
 
 # -----------------------------------------------------------------------------
-# Security & Authentication (for future auth system)
+# Security & Authentication
 # -----------------------------------------------------------------------------
 
 # Secret key for JWT tokens (generate with: python -c "import secrets; print(secrets.token_hex(32))")
@@ -84,3 +90,19 @@ CARD_JOKER=-2
 CARD_SUPER_KINGS=-2         # King value when super_kings enabled
 CARD_TEN_PENNY=1            # 10 value when ten_penny enabled
 CARD_LUCKY_SWING_JOKER=-5   # Joker value when lucky_swing enabled
+
+# -----------------------------------------------------------------------------
+# Production Features (Optional)
+# -----------------------------------------------------------------------------
+
+# Sentry error tracking
+# SENTRY_DSN=https://your-sentry-dsn
+
+# Resend API for emails (required for user registration/password reset)
+# RESEND_API_KEY=your-api-key
+
+# Enable rate limiting (recommended for production)
+# RATE_LIMIT_ENABLED=true
+
+# Base URL for email links
+# BASE_URL=https://your-domain.com