docs(env): improve .env.example with detailed cache directory configurations

Author: erfanMhi

.env.example

@@ -256,8 +256,35 @@ GRAIL_CHECKPOINT_RETENTION_LIMIT=3
 GRAIL_CHECKPOINT_MILESTONE_INTERVAL=100
 
 # Local cache directory for checkpoints (default: ~/.cache/grail)
+#
+# IMPORTANT:
+# - If left blank, defaults to ~/.cache/grail (persistent on disk)
+# - Empty strings should NOT be used as they can cause path resolution issues
+#
+# Recommended for faster checkpoint I/O (RAM disk / tmpfs):
+#   GRAIL_CACHE_DIR=/dev/shm/grail
+#
+# Example (persistent on disk):
+#   GRAIL_CACHE_DIR=/home/user/.cache/grail
+#
+# Leave blank to use default (~/.cache/grail):
 GRAIL_CACHE_DIR=
 
+# HuggingFace models cache directory (default: ~/.cache/huggingface)
+#
+# IMPORTANT:
+# - Redirects all HuggingFace model downloads (AutoModel, AutoTokenizer)
+# - If left blank, HuggingFace defaults to ~/.cache/huggingface
+#
+# Recommended for faster model I/O (RAM disk / tmpfs):
+#   HF_HOME=/dev/shm/huggingface
+#
+# Example (persistent on disk):
+#   HF_HOME=/home/user/.cache/huggingface
+#
+# Leave blank to use default (~/.cache/huggingface):
+HF_HOME=
+
 # ============================================================================
 # MONITORING SYSTEM CONFIGURATION
 # ============================================================================