diff --git a/app/services/ai/llm_service.py b/app/services/ai/llm_service.py
index 89b04ab..69a95a9 100644
--- a/app/services/ai/llm_service.py
+++ b/app/services/ai/llm_service.py
@@ -10,6 +10,8 @@ from app.core.settings import settings
 from app.models.tool_model import ToolDefinition
 
 
+# Essa classe encapsula a integracao com o Vertex AI:
+# inicializacao, cache de modelos e serializacao das tools.
 class LLMService:
     _vertex_initialized = False
     _models: dict[str, GenerativeModel] = {}
@@ -83,6 +85,8 @@ class LLMService:
         response = None
         last_error = None
 
+        # Tenta o modelo configurado e cai para nomes alternativos
+        # quando o principal nao estiver disponivel no projeto/regiao.
         for model_name in self.model_names:
             try:
                 model = self._get_model(model_name)
diff --git a/app/services/orchestration/conversation_state_repository.py b/app/services/orchestration/conversation_state_repository.py
index 8293f12..7df8b10 100644
--- a/app/services/orchestration/conversation_state_repository.py
+++ b/app/services/orchestration/conversation_state_repository.py
@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 
 
+# Interface base para qualquer backend de estado conversacional.
 class ConversationStateRepository(ABC):
     @abstractmethod
     def upsert_user_context(self, user_id: int | None, ttl_minutes: int) -> None:
diff --git a/app/services/orchestration/conversation_state_store.py b/app/services/orchestration/conversation_state_store.py
index 55f48b9..2f12d68 100644
--- a/app/services/orchestration/conversation_state_store.py
+++ b/app/services/orchestration/conversation_state_store.py
@@ -3,6 +3,8 @@ from datetime import datetime, timedelta
 from app.services.orchestration.conversation_state_repository import ConversationStateRepository
 
 
+# Implementacao local em memoria do estado conversacional.
+# Serve como fallback simples para desenvolvimento e testes.
 class ConversationStateStore(ConversationStateRepository):
     def __init__(self) -> None:
         self.user_contexts: dict[int, dict] = {}
diff --git a/app/services/orchestration/orchestrator_config.py b/app/services/orchestration/orchestrator_config.py
index 3b24bb8..10f9ece 100644
--- a/app/services/orchestration/orchestrator_config.py
+++ b/app/services/orchestration/orchestrator_config.py
@@ -1,3 +1,5 @@
+# Constantes compartilhadas do orquestrador:
+# TTLs, campos obrigatorios, respostas de baixo valor e tools especiais.
 USER_CONTEXT_TTL_MINUTES = 60
 PENDING_ORDER_SELECTION_TTL_MINUTES = 15
 
diff --git a/app/services/orchestration/prompt_builders.py b/app/services/orchestration/prompt_builders.py
index 93e8845..26f7635 100644
--- a/app/services/orchestration/prompt_builders.py
+++ b/app/services/orchestration/prompt_builders.py
@@ -1,6 +1,7 @@
 from typing import Any
 
 
+# Builders centralizados dos prompts usados pelo orquestrador.
 def _build_user_context_line(user_id: int | None) -> str:
     return f"Contexto de usuario autenticado: user_id={user_id}.\n" if user_id else ""
 
diff --git a/app/services/orchestration/redis_state_repository.py b/app/services/orchestration/redis_state_repository.py
index 532b449..514bef2 100644
--- a/app/services/orchestration/redis_state_repository.py
+++ b/app/services/orchestration/redis_state_repository.py
@@ -7,6 +7,7 @@ from redis import Redis
 from app.services.orchestration.conversation_state_repository import ConversationStateRepository
 
 
+# Implementacao persistida do estado conversacional usando Redis e TTL.
 class RedisConversationStateRepository(ConversationStateRepository):
     def __init__(
         self,
diff --git a/app/services/orchestration/state_repository_factory.py b/app/services/orchestration/state_repository_factory.py
index 346d84b..369013e 100644
--- a/app/services/orchestration/state_repository_factory.py
+++ b/app/services/orchestration/state_repository_factory.py
@@ -6,6 +6,7 @@ from app.services.orchestration.conversation_state_store import ConversationStat
 _state_repository: ConversationStateRepository | None = None
 
 
+# Resolve e memoiza o backend de estado configurado para o processo atual.
 def get_conversation_state_repository() -> ConversationStateRepository:
     global _state_repository
     if _state_repository is not None:
diff --git a/app/services/orchestration/tool_executor.py b/app/services/orchestration/tool_executor.py
index 5b8ad82..2f4b0df 100644
--- a/app/services/orchestration/tool_executor.py
+++ b/app/services/orchestration/tool_executor.py
@@ -4,6 +4,7 @@ from app.services.orchestration.orchestrator_config import DETERMINISTIC_RESPONS
 from app.services.orchestration.response_formatter import fallback_format_tool_result
 
 
+# Camada fina para executar tools e padronizar o retorno de erros.
 class ToolExecutor:
     def __init__(self, registry):
         self.registry = registry
diff --git a/app/services/tools/tool_registry.py b/app/services/tools/tool_registry.py
index afce663..a7ade46 100644
--- a/app/services/tools/tool_registry.py
+++ b/app/services/tools/tool_registry.py
@@ -31,6 +31,7 @@ HANDLERS: Dict[str, Callable] = {
 }
 
 
+# Registry em memoria das tools disponiveis para o orquestrador.
 class ToolRegistry:
 
     def __init__(self, db: Session, extra_handlers: Dict[str, Callable] | None = None):
diff --git a/app/services/user/mock_customer_service.py b/app/services/user/mock_customer_service.py
index f32371a..082393e 100644
--- a/app/services/user/mock_customer_service.py
+++ b/app/services/user/mock_customer_service.py
@@ -4,6 +4,7 @@ from app.db.mock_database import SessionMockLocal
 from app.db.mock_models import Customer, User
 
 
+# Helpers para criar clientes ficticios deterministas a partir do CPF.
 MOCK_CUSTOMER_NAMES = [
     "Ana Souza",
     "Bruno Lima",
diff --git a/app/services/user/user_service.py b/app/services/user/user_service.py
index 60f28a5..482950d 100644
--- a/app/services/user/user_service.py
+++ b/app/services/user/user_service.py
@@ -3,6 +3,7 @@ from sqlalchemy.orm import Session
 from app.repositories.user_repository import UserRepository
 
 
+# Servico simples de identidade por canal externo.
 class UserService:
     def __init__(self, db: Session):
         """Inicializa o servico de usuarios com repositorio persistente."""