feat: add optional comment field to StateMachineDefinition

[ottobot-ai]

Background

SDK state machine JSON definitions include documentation fields that OttoChain's strict decoder rejects. The _ prefix is reserved for fiber engine processing, so we need a different approach.

Proposal

Add an optional comment field to StateMachineDefinition (and possibly other schema types):

case class StateMachineDefinition(
  states:       Map[StateId, State],
  initialState: StateId,
  transitions:  List[Transition],
  metadata:     Option[JsonLogicValue] = None,
  comment:      Option[String] = None  // NEW: documentation field
)

Alternatives Considered

1. _comment - Conflicts with reserved key convention (_ prefix = engine processing)
2. Lenient decoding - Would silently ignore typos, prefer explicit fields
3. Strip in SDK - Current workaround (PR feat(validation): reject reserved JSON Logic operators as field names #14), but loses documentation

Acceptance Criteria

• Add comment: Option[String] to StateMachineDefinition
• Consider adding to State and Transition as well
• Update SDK to use comment instead of _comment

Related

• SDK PR feat(validation): reject reserved JSON Logic operators as field names #14: temporary fix removing initialDataTemplate and _comment fields
• Reserved keys: ReservedKeys.scala