diff --git a/src/.env.example b/src/.env.example
index 6fc93a4..58b1dea 100644
--- a/src/.env.example
+++ b/src/.env.example
@@ -154,6 +154,20 @@ DB_PASSWORD=your_secure_password_here
 # Master switch: Set to false for completely free play (no wallet needed)
 PAYMENTS_ENABLED=true
 
+# FREE_PLAY_ENABLED: offer FREE play as a CHOICE even when payments are on. Free games
+# are recorded as game_mode=FREE and appear on the Pleb leaderboard (NOT the Hall of
+# Champions, which is for paid games). Always effectively on when PAYMENTS_ENABLED=false.
+#
+#   DEPLOYMENT PATTERNS
+#   • Real-money / mainnet (legitimacy): free-to-play + sell credits/entry, but NO PAYOUTS.
+#     Players pay for prestige (Hall of Champions), not crypto winnings — not gambling.
+#       PAYMENTS_ENABLED=true  FREE_PLAY_ENABLED=true  PAYOUTS_ENABLED=false
+#       DIRECT_PAYOUTS_ENABLED=false  CREDITS_PAYOUTS_ENABLED=false
+#       DIRECT_REQUIRES_ADDRESS=false CREDITS_REQUIRES_ADDRESS=false   (no payout = no address)
+#   • Test/stagenet (fake money): full pay-to-play WITH payouts is fine.
+#       PAYMENTS_ENABLED=true  PAYOUTS_ENABLED=true  *_PAYOUTS_ENABLED=true
+FREE_PLAY_ENABLED=false
+
 # Which payment modes to enable (comma-separated)
 PAYMENT_MODES=direct,credits