Refactor codebase into modular API for easier use and clarity

[andrewrosemberg]

Problem: The current code (e.g., simulate_multistage.jl) bundles simulation, parameter-setting, and manual differentiation logic in a single file. Functions use generic vector arguments (state_param_in/out) and manually coded rrules, making it difficult for new users to understand or extend the package.

Proposed solution:

• Separate modules: Create submodules within DecisionRules.jl (e.g., Simulation, Policies, Training). Move simulate_multistage and helper functions into a dedicated Simulation module. Similarly, group neural network–related functions in a Policies module.

• Define clear types: Introduce typed structs for the problem (e.g., DecisionRuleProblem) encapsulating state variables, control variables, constraints, and cost functions. A DecisionRulePolicy struct can wrap the neural network or linear rule.

• Expose high‑level functions: Provide a high‑level API, such as simulate(problem, policy, initial_state, uncertainties), that hides internal parameter-setting and solver calls. Users should not need to manipulate subproblem parameters manually.

• Docstrings and examples: Add comprehensive docstrings for each public function and provide minimal working examples in the examples/ folder (e.g., the battery test case).

• Testing: Add unit tests covering the new high‑level functions, ensuring they match the current logic and outputs.

• Documentation: Fix readme and possibly also add documentation already.